/**
 * swagger.js - Swagger API文档配置
 * 
 * 这个模块使用swagger-jsdoc从代码注释中自动生成API文档。
 * 它定义了API的基本信息、服务器URL和安全方案。
 */

const swaggerJsdoc = require('swagger-jsdoc');
const config = require('./index');

/**
 * Swagger选项配置
 */
const options = {
  definition: {
    openapi: '3.0.0',
    info: {
      title: '企业级Express API',
      version: config.api.version,
      description: '企业级Express API项目文档',
      license: {
        name: 'MIT',
        url: 'https://opensource.org/licenses/MIT',
      },
      contact: {
        name: 'API Support',
        url: 'https://example.com/support',
        email: 'support@example.com',
      },
    },
    servers: [
      {
        url: `http://localhost:${config.app.port}${config.api.prefix}`,
        description: '开发服务器',
      },
    ],
    // 安全方案定义
    components: {
      securitySchemes: {
        bearerAuth: {
          type: 'http',
          scheme: 'bearer',
          bearerFormat: 'JWT',
        },
      },
      // 通用响应定义
      responses: {
        UnauthorizedError: {
          description: '未授权访问',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  status: {
                    type: 'string',
                    example: 'error',
                  },
                  code: {
                    type: 'integer',
                    example: 401,
                  },
                  message: {
                    type: 'string',
                    example: '未授权访问',
                  },
                },
              },
            },
          },
        },
        NotFoundError: {
          description: '资源未找到',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  status: {
                    type: 'string',
                    example: 'error',
                  },
                  code: {
                    type: 'integer',
                    example: 404,
                  },
                  message: {
                    type: 'string',
                    example: '请求的资源未找到',
                  },
                },
              },
            },
          },
        },
        ValidationError: {
          description: '请求验证错误',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  status: {
                    type: 'string',
                    example: 'error',
                  },
                  code: {
                    type: 'integer',
                    example: 400,
                  },
                  message: {
                    type: 'string',
                    example: '请求参数验证失败',
                  },
                  errors: {
                    type: 'array',
                    items: {
                      type: 'object',
                      properties: {
                        field: {
                          type: 'string',
                          example: 'email',
                        },
                        message: {
                          type: 'string',
                          example: '必须是有效的电子邮件地址',
                        },
                      },
                    },
                  },
                },
              },
            },
          },
        },
        ServerError: {
          description: '服务器错误',
          content: {
            'application/json': {
              schema: {
                type: 'object',
                properties: {
                  status: {
                    type: 'string',
                    example: 'error',
                  },
                  code: {
                    type: 'integer',
                    example: 500,
                  },
                  message: {
                    type: 'string',
                    example: '服务器内部错误',
                  },
                },
              },
            },
          },
        },
      },
      // 通用请求体和响应模式
      schemas: {
        // 示例用户模式
        User: {
          type: 'object',
          properties: {
            id: {
              type: 'string',
              format: 'uuid',
              description: '用户唯一标识符',
            },
            username: {
              type: 'string',
              description: '用户名',
            },
            email: {
              type: 'string',
              format: 'email',
              description: '电子邮件地址',
            },
            createdAt: {
              type: 'string',
              format: 'date-time',
              description: '创建时间',
            },
            updatedAt: {
              type: 'string',
              format: 'date-time',
              description: '更新时间',
            },
          },
        },
        // 通用错误响应
        Error: {
          type: 'object',
          properties: {
            status: {
              type: 'string',
              example: 'error',
            },
            code: {
              type: 'integer',
              example: 400,
            },
            message: {
              type: 'string',
            },
          },
        },
        // 通用成功响应
        Success: {
          type: 'object',
          properties: {
            status: {
              type: 'string',
              example: 'success',
            },
            data: {
              type: 'object',
              description: '响应数据',
            },
          },
        },
      },
    },
    // 全局安全要求
    security: [
      {
        bearerAuth: [],
      },
    ],
  },
  // 指定API路由文件的路径模式
  apis: ['./src/routes/*.js', './src/models/*.js'],
};

/**
 * 使用swagger-jsdoc生成Swagger规范
 */
const swaggerSpec = swaggerJsdoc(options);

module.exports = swaggerSpec;